README LINUX

   1 -*-text-*---------------------------------------------------------------
   2 supercollider 3 for linux
   3 ------------------------------------------------------------------------
   4 $Id$
   5 ------------------------------------------------------------------------
   6
   7 ------------------------------------------------------------------------
   8 intro
   9 ------------------------------------------------------------------------
  10
  11 SuperCollider is a synthesis engine (scsynth) and programming language
  12 (sclang), originally Mac-based but now very widely used on Linux
  13 (since Stefan Kersten ported the code in 2003). SuperCollider is free
  14 software under the GPL - its main homepage is at
  15
  16    http://supercollider.sourceforge.net
  17
  18 to get further information on supercollider usage or development, you
  19 might consider subscribing to the mailing lists
  20
  21   http://www.beast.bham.ac.uk/research/sc_mailing_lists.shtml
  22
  23 ------------------------------------------------------------------------
  24 build requirements
  25 (most of these will be available in your linux distribution as packages )
  26 ------------------------------------------------------------------------
  27
  28  * gcc >= 3.0
  29    http://www.gnu.org/software/gcc/
  30    gcc versions < 3.0 are missing some required c++ features
  31
  32  * jack and libjack
  33    http://jackit.sourceforge.net/
  34    jack audio connection kit
  35
  36  * libsndfile >= 1.0
  37    http://www.mega-nerd.com/libsndfile/
  38    _the_ soundfile i/o library
  39
  40  * pkg-config >= 0.14.0
  41    http://www.freedesktop.org/software/pkgconfig/
  42    facilitates checking for installed packages when compiling from
  43    source
  44
  45  * scons >= 0.96
  46    http://www.scons.org/
  47    configuration and build tool based on python
  48
  49  * fftw >= 3.0
  50    http://www.fftw.org/
  51    fast FFT transform library (for frequency-domain analysis,
  52                                         phase-vocoder effects)
  53
  54 ------------------------------------------------------------------------
  55 build requirements (optional features)
  56 (most of these will be available in your linux distribution as packages )
  57 ------------------------------------------------------------------------
  58
  59  * alsa
  60    http://www.alsa-project.org/
  61    advanced linux sound architecture drivers and library, for sclang's
  62    MIDI interface
  63
  64  * libreadline >= 5
  65    http://savannah.gnu.org/projects/readline
  66    provides convenient CLI interface for sclang
  67    (if unavailable, set READLINE=0 as an argument to scons)
  68
  69  * libhowl (obsolete)
  70    http://www.porchdogsoft.com/products/howl/
  71    zeroconf service dicovery implementation
  72
  73  * libavahi-client
  74    http://www.avahi.org/
  75    a more powerful zeroconf service discovery implementation
  76
  77  * linux kernel >= 2.6
  78    http://www.kernel.org/
  79    for sclang's linux input device (LID) interface
  80
  81  * for scel: the Emacs interface see the README in the directory
  82    `editors/scel'
  83
  84  * for sced: the gedit interface see the README in the directory
  85    `editors/sced'
  86
  87  * for scvim: the vim interface see the README in the directory
  88    `editors/scvim'
  89
  90
  91 ------------------------------------------------------------------------
  92 build requirements (debian users)
  93 ------------------------------------------------------------------------
  94
  95 on debian (unstable) you can install the following packages and be set
  96 for building supercollider:
  97
  98    gcc
  99    libjack0.100.0-dev
 100    libsndfile1-dev
 101    libasound2-dev
 102    libavahi-client-dev
 103    libreadline6-dev
 104    libfftw3-dev
 105    pkg-config
 106    scons
 107
 108 ------------------------------------------------------------------------
 109 building
 110 ------------------------------------------------------------------------
 111
 112 building with scons is not really different from building with
 113 autoconf, automake and related tools.
 114
 115    $ scons -H
 116
 117 gives an overview of scons options.
 118
 119    $ scons -h
 120
 121 lists package specific options variables and their default values.
 122 (Note: some options allow to disable the dependencies on fftw and on
 123 libsndfile, but those dependencies should be considered compulsory for
 124 most standard setups since they provide much core sc functionality.)
 125
 126 options can be set on the command line
 127
 128    $ scons VARIABLE=VALUE
 129
 130 and are cached in a file called scache.conf (which can be edited with
 131 your favorite editor) for use in the next scons invocation.
 132
 133 in order to build the whole package, call scons without arguments
 134 (apart from option variables). in order to install the package, call
 135 scons with the `install' target:
 136
 137    $ scons install
 138
 139 any target (including `install') can be cleaned with the `-c' option
 140 to scons; note that cleaning the `install' target also removes locally
 141 built files.
 142
 143 The option SCEL installs the emacs editor. For the sced and scvim editors,
 144 please use the scons scripts in their respective directories (in editors/).
 145
 146 Note that the language will only build 32bit. To compile the language as
 147 32bit binary on a 64bit installation, a multilib compiler and 32bit
 148 libraries are required (on debian systems, the packages are gcc-multilib
 149 g++-multilib, ia32-libs, libc6-dev-i386 and lib32asound2-dev).
 150
 151
 152 ------------------------------------------------------------------------
 153 Building a Debian package
 154 ------------------------------------------------------------------------
 155
 156 In our SVN we have debian packaging rules. These were designed on Ubuntu
 157 but we believe they should work on most common debian systems - please
 158 let us know if you have any issues with this way of building:
 159
 160   cd SuperCollider3    # (or wherever your SC source is)
 161   svn co https://supercollider.svn.sourceforge.net/svnroot/supercollider/packages/ubuntu/ debian
 162   debuild
 163
 164 Eventually, some .deb packages will be put in the parent folder, and can
 165 then be installed just like any other Debian package. For example:
 166
 167   dpkg -i ../supercollider*.deb
 168
 169 (Note: the packages supercollider-scel*.deb, supercollider-scvim*.deb,
 170 supercollider-sced*.deb, represent the different editor integrations:
 171 emacs, vim, gedit. You might not want to install all of those, but
 172 choose your preferred editor.)
 173
 174
 175 ------------------------------------------------------------------------
 176 running scsynth (standalone)
 177 ------------------------------------------------------------------------
 178
 179 run scsynth without options to get an option summary. don't forget to
 180 start jackd before trying to use scsynth. if you want to add
 181 directories to supercollider's search path or assign default jack
 182 ports, set up your environment as described below.
 183
 184 you can specify the number of jack input/output channels created with
 185 the options -i and -o, respectively.
 186
 187 the -H option can be used to specify a jack server to connect to and
 188 to set the jack client identifier. the format is either
 189
 190     <SERVER-NAME>:<CLIENT-NAME>
 191
 192 or just
 193
 194     <CLIENT-NAME>
 195
 196 when connecting to the default server.
 197
 198 ------------------------------------------------------------------------
 199 running sclang
 200 ------------------------------------------------------------------------
 201
 202 it is recommended to use sclang in combination with your preferred text
 203 editor out of emacs/vim/gedit. see the README files in `linux/*' for
 204 installation and usage. as an alternative you can simply run the
 205 `sclang' executable which will provide a readline-based interface.
 206
 207 sclang executes the startup file `~/.sclang.sc' after class library
 208 initialization. this file can contain statements to set up your
 209 supercollider environment, like setting default variables. an example can
 210 be found in `linux/examples/sclang.sc'.
 211
 212 you _have_ to have a directory `~/share/SuperCollider/'. This is where
 213 automatically a synthdefs directory is created. It is also the place
 214 to put Extensions to the class library, in a folder called Extensions.
 215
 216 the runtime directory is either the current working directory or the
 217 path specified with the `-d' option.
 218
 219 for advanced setups, sclang's compilation search path can be
 220 customized with a library configuration file. an example is provided
 221 in `linux/examples/sclang.cfg'; install it as `/etc/sclang.cfg' or
 222 `~/.sclang.cfg'. This config file is only needed when you want to
 223 _exclude_ directories from the class library. Otherwise (so in most cases)
 224 it is not needed.
 225
 226 ------------------------------------------------------------------------
 227 environment
 228 ------------------------------------------------------------------------
 229
 230 the jack audio driver interface is configured based on various
 231 environment variables:
 232
 233  * SC_JACK_DEFAULT_INPUTS comma separated list of jack ports that
 234    scsynth's inputs should connect to by default
 235
 236    $ export SC_JACK_DEFAULT_INPUTS="system:capture_1,system:capture_2"
 237
 238    in order to connect the first ports of one jack client, it is possible
 239    to specify only the client name
 240
 241    $ export SC_JACK_DEFAULT_INPUTS="system"
 242
 243  * SC_JACK_DEFAULT_OUTPUTS comma separated list of jack ports that
 244    scsynth's outputs should be connected to by default.
 245
 246    $ export SC_JACK_DEFAULT_OUTPUTS="system:playback_1,system:playback_2"
 247
 248    in order to connect the first ports of one jack client, it is possible
 249    to specify only the client name
 250
 251    $ export SC_JACK_DEFAULT_OUTPUTS="system"
 252
 253 two additional environment variables substitute directories for the default
 254 search path for plugins and synth definitions, respectively. directory
 255 names are separated by ':' as in the unix PATH variable:
 256
 257  * SC_PLUGIN_PATH, SC_SYNTHDEF_PATH
 258
 259    $ export SC_SYNTHDEF_PATH="./synthdefs:/home/sk/SuperCollider/synthdefs"
 260
 261 ------------------------------------------------------------------------
 262 documentation
 263 ------------------------------------------------------------------------
 264
 265 apart from the sites listed above, some more documentation links ...
 266
 267 a wiki for supercollider, set up by julian rohrhuber, is at
 268
 269     http://swiki.hfbk-hamburg.de/MusicTechnology/6
 270
 271 linux specific information can be found at
 272
 273     http://swiki.hfbk-hamburg.de/MusicTechnology/478
 274
 275 ------------------------------------------------------------------------
 276 reporting bugs
 277 ------------------------------------------------------------------------
 278
 279 please report bugs either to the sc-users or sc-dev mailing lists.
 280
 281 ------------------------------------------------------------------------
 282 contributors to this document
 283 ------------------------------------------------------------------------
 284
 285 stefan kersten <sk AT k-hornz DOT de>
 286 andi pieper
 287 maurizio umberto puxeddu
 288 rohan drape
 289 mario lang
 290 john yates
 291 nescivi (marije baalman)
 292 dan stowell
 293
 294 ------------------------------------------------------------------------
 295 outro
 296 ------------------------------------------------------------------------
 297
 298 thanks to james mccartney, for making this great piece of audio
 299 software publically and freely available.
 300
 301 ------------------------------------------------------------------------
 302 eof
 303 ------------------------------------------------------------------------
 304